home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 2000 November: Tool Chest / Dev.CD Nov 00 TC Disk 1.toast / Sample Code / Networking / MoreNetworkSetup / NetworkSetup / NetworkSetupHelpers.h < prev    next >
Encoding:
C/C++ Source or Header  |  2000-09-28  |  15.7 KB  |  356 lines  |  [TEXT/CWIE]
  1. /*
  2.     File:        NetworkSetupHelpers.h
  3.  
  4.     Contains:    High-level network preference routines.
  5.  
  6.     Written by:    Quinn
  7.  
  8.     Copyright:    Copyright © 1998 by Apple Computer, Inc., all rights reserved.
  9.  
  10.                 You may incorporate this Apple sample source code into your program(s) without
  11.                 restriction. This Apple sample source code has been provided "AS IS" and the
  12.                 responsibility for its operation is yours. You are not permitted to redistribute
  13.                 this Apple sample source code as "Apple sample source code" after having made
  14.                 changes. If you're going to re-distribute the source, we require that you make
  15.                 it clear in the source that the code was descended from Apple sample source
  16.                 code, but that you've made changes.
  17.  
  18.     Change History (most recent first):
  19.  
  20.         <14>     18/1/00    Quinn   Further updates for the new Network Setup header file.
  21.         <13>     17/1/00    Quinn   Updates for latest Network Setup headers.
  22.         <12>     7/10/99    Quinn   Comments to cover common "gotcha" cases, thanks to John Norstad.
  23.         <11>     22/9/99    Quinn   Fixed two 'backward branches' in the comments.  Thanks to John
  24.                                     Norstad.
  25.         <10>     13/9/99    Quinn   Implement DHCPRelease.
  26.          <9>     26/5/99    Quinn   Tidied up C++ #if's.  Added cookie4 to NSHConfigurationEntry to
  27.                                     hold protocol type, and thus removed the protocol parameter from
  28.                                     NSHSelectConfiguration.  Improved comments.
  29.          <8>      7/5/99    Quinn   This "redux" word, I don't think it means what you think it
  30.                                     means.
  31.          <7>     22/4/99    Quinn   Added MNSEncodeRemotePassword.
  32.          <6>     21/4/99    Quinn   Added interface to routines which create, duplicate, get, set,
  33.                                     delete and rename configurations for TCP/IP, Remote Access, and
  34.                                     Modem.
  35.          <5>    10/11/98    Quinn   Convert "MorePrefix.h" to "MoreSetup.h".
  36.          <4>     9/11/98    Quinn   AppleTalk on/off support.
  37.          <3>     9/11/98    Quinn   Add "TCP will dial" code.
  38.          <2>     5/11/98    Quinn   Fix header.
  39.          <1>     5/11/98    Quinn   First checked in.
  40. */
  41.  
  42. #pragma once
  43.  
  44. /////////////////////////////////////////////////////////////////
  45. // MoreIsBetter Setup
  46.  
  47. #include "MoreSetup.h"
  48.  
  49. /////////////////////////////////////////////////////////////////
  50. // Mac OS Interfaces
  51.  
  52. #include <MacTypes.h>
  53. #include <NetworkSetup.h>
  54.  
  55. #ifdef __cplusplus
  56. extern "C" {
  57. #endif
  58.  
  59. /////////////////////////////////////////////////////////////////
  60. // Routines to Enumerate and Switch TCP/IP and AppleTalk Preferences
  61.  
  62. struct NSHConfigurationEntry {
  63.     Str255     name;                    // user-visible name of the configuration
  64.     Boolean selected;                // true if this configuration is currently active
  65.     SInt16     cookie;                    // cookies for use by this library
  66.     CfgEntityRef cookie2;
  67.     CfgEntityInfo cookie3;
  68.     OSType    cookie4;
  69. };
  70. typedef struct NSHConfigurationEntry NSHConfigurationEntry;
  71. typedef NSHConfigurationEntry *NSHConfigurationListPtr;
  72. typedef NSHConfigurationListPtr *NSHConfigurationListHandle;
  73.  
  74. extern pascal ItemCount NSHCountConfigurationList(NSHConfigurationListHandle configList);
  75.     // Returns a count of the number of entries in configList.
  76.     
  77. extern pascal OSStatus  NSHGetConfigurationList(OSType protocol, NSHConfigurationListHandle configList);
  78.     // Reads the list of configurations for the specific protocol,
  79.     // placing a NSHConfigurationEntry in configList for each one.
  80.     // configList must be a non-locked handle allocated by you.
  81.     // The routine will resize it appropriate.  Specify protocol
  82.     // using one of the constants declared in "NetworkSetup.h".
  83.     // Currently handles the following protocols:
  84.     //   o kOTTCPv4NetworkConnection
  85.     //   o kOTAppleTalkNetworkConnection
  86.     //   o kOTRemoteNetworkConnection
  87.     //   o kOTModemNetworkConnection
  88.  
  89. extern pascal OSStatus  NSHSelectConfiguration(const NSHConfigurationEntry *chosenEntry);
  90.     // Given an entry from the configList generated by the previous
  91.     // routine, this routine switches the network protocol to use
  92.     // that configuration.
  93.     //
  94.     // Note: In earlier versions of this sample, this routine took a
  95.     // "protocol" parameter.  It no longer needs this parameter because
  96.     // the protocol is now stored in one of the cookies in the
  97.     // NSHConfigurationEntry.
  98.  
  99. /////////////////////////////////////////////////////////////////
  100. // Routines for Internet Setup Software
  101.  
  102. // ----- TCP/IP -----
  103.  
  104. struct NSHTCPv4ConfigurationDigest {
  105.     OSType                fProtocol;            // always kOTTCPv4NetworkConnection for NSHTCPv4ConfigurationDigest
  106.     Str255                 fConfigName;        // user-visible name of the configuration
  107.     OTPortRef            fPortRef;            // OT port for the config (lookup “ddp1” for MacIP)
  108.                                             // "Connect via" in the UI
  109.     OTCfgTCPConfigMethod fConfigMethod;        // one of the constants given above
  110.                                             // "Configure:" in the UI
  111.                                             // For "PPP Server", use kOTCfgManualConfig with fIPAddress of 0
  112.     InetHost            fIPAddress;            // IP address
  113.     InetHost            fSubnetMask;        // IP subnet mask
  114.     Handle                fRouterList;        // array of InetHost
  115.     Handle                fDNSServerList;        // list of DNS servers, array of InetHost
  116.     Str255                fLocalDomain;        // the local domain for this machine
  117.                                             // "Implicit Search Path: Starting domain name:" in the UI
  118.     Str255                fAdminDomain;        // "Implicit Search Path: Ending domain name:" in the UI
  119.     Handle                fSearchDomains;        // STR# format
  120.     Str32                fAppleTalkZone;        // for MacIP only, specify empty string otherwise
  121.     UInt32                fFraming;            // framing attributes for this port
  122.                                             // "Use 802.3" in the UI
  123.                                             // Only for port with device type kOTEthernetDevcie
  124.                                             // - use kOTFramingEthernet by default
  125.                                             // - use kOTFraming8022 if the 802.3 checkbox is set
  126.                                             // Set to 0 for non-Ethernet ports
  127.     OTCfgTCPUnloadAttr    fUnloadAttr;        // one of the constants given above
  128.     Str255                fHintUserVisiblePortName;    // Hints to find the port name if fPortRef is kOTInvalidPortRef
  129.     Str63                fHintPortName;
  130.     Str63                fHintDriverName;
  131.     UInt16                fHintDeviceType;
  132. };
  133. typedef struct NSHTCPv4ConfigurationDigest NSHTCPv4ConfigurationDigest;
  134.  
  135. // ----- Remote Access -----
  136.  
  137. struct NSHRemoteConfigurationDigest {
  138.     OSType                fProtocol;                    // always kOTRemoteNetworkConnection for NSHRemoteConfigurationDigest
  139.     Str255                 fConfigName;                // user-visible name of the configuration
  140.     
  141.     // Main panel in UI
  142.     
  143.     Boolean                fGuestLogin;                // 
  144.     Boolean                fPasswordValid;                // 
  145.     Str255                fUserName;                    // only valid if fGuestLogin is false
  146.     Str255                fPassword;                    // only valid if fGuestLogin is false and fPasswordValid is true
  147.     Str255                fPhoneNumber;                //
  148.     
  149.     // Dialling tab in UI
  150.     
  151.     OTCfgRemoteRedialMode fRedialMode;                // one of the constants in "NetworkSetup.h"
  152.     UInt32                fRedialTimes;                // only valid if fRedialOptions != kRemoteRedialNone
  153.     UInt32                fRedialDelay;                // (ms) only valid if fRedialOptions != kRemoteRedialNone
  154.     Str255                fAlternatePhoneNumber;        // only valid if fRedialOptions == kRemoteRedialMainAndAlternate
  155.  
  156.     // Connection tab in UI
  157.     
  158.     Boolean                fVerboseLogging;            //
  159.     Boolean                fFlashIconWhileConnected;    //
  160.     Boolean                fPromptToRemainConnected;    //
  161.     UInt32                fPromptInterval;            // (minutes)
  162.     Boolean                fDisconnectIfIdle;            //
  163.     UInt32                fDisconnectInterval;        // (ms)
  164.     
  165.     // Protocol tab in UI
  166.     
  167.     OTCfgRemoteProtocol    fSerialProtocol;            // one of the constants in "NetworkSetup.h"
  168.     Boolean                fPPPConnectAutomatically;            // only valid if fSerialProtocol == kRemoteProtocolPPP
  169.     Boolean                fPPPAllowModemCompression;            // only valid if fSerialProtocol == kRemoteProtocolPPP
  170.     Boolean                fPPPAllowTCPIPHeaderCompression;    // only valid if fSerialProtocol == kRemoteProtocolPPP
  171.     OTCfgRemotePPPConnectScript fPPPConnectMode;            // only valid if fSerialProtocol == kRemoteProtocolPPP, one of the constants given above
  172.     Str63                fPPPConnectScriptName;                // only valid if fPPPConnectMode == kOTCfgRemotePPPConnectScriptScript
  173.     Handle                fPPPConnectScript;                    // only valid if fPPPConnectMode == kOTCfgRemotePPPConnectScriptScript
  174. };
  175. typedef struct NSHRemoteConfigurationDigest NSHRemoteConfigurationDigest;
  176.  
  177. // ----- Modem -----
  178.  
  179. struct NSHModemConfigurationDigest {
  180.     OSType                     fProtocol;            // always kOTModemNetworkConnection for NSHModemConfigurationDigest
  181.     Str255                      fConfigName;        // user-visible name of the configuration
  182.     OTPortRef                 fPortRef;            // reference to OT serial port
  183.     FSSpec                      fModemScript;        // reference to CCL file
  184.     OTCfgModemDialogToneMode fDialToneMode;        // one of the constants in "NetworkSetup.h"
  185.     Boolean                  fSpeakerOn;            // turn on speaker
  186.     Boolean                  fPulseDial;            // use pulse dial
  187.     Str63                      fHintPortName;        // Hint to find the port name if fPortRef is kOTInvalidPortRef
  188. };
  189. typedef struct NSHModemConfigurationDigest NSHModemConfigurationDigest;
  190.  
  191. // ----- Generic -----
  192.  
  193. // NSHConfigurationDigestCommon describes the fields that must
  194. // be at the front of all protocol-specific configuration digest
  195. // records.
  196.  
  197. struct NSHConfigurationDigestCommon {
  198.     OSType                fProtocol;            // protocol of the configuration
  199.     Str255                 fConfigName;        // user-visible name of the configuration
  200. };
  201. typedef struct NSHConfigurationDigestCommon NSHConfigurationDigestCommon;
  202.  
  203. // NSHConfigurationDigest is a union of all the protocol-specific
  204. // configuration digest records defined above.
  205.  
  206. union NSHConfigurationDigest {
  207.     NSHConfigurationDigestCommon fCommon;
  208.     NSHTCPv4ConfigurationDigest  fTCPv4;
  209.     NSHRemoteConfigurationDigest fRemote;
  210.     NSHModemConfigurationDigest  fModem;
  211. };
  212. typedef union NSHConfigurationDigest NSHConfigurationDigest;
  213.  
  214. extern pascal OSStatus NSHCreateConfiguration(const NSHConfigurationDigest *configurationDigest,
  215.                                                 NSHConfigurationEntry *createdConfig);
  216.     // Creates a new connection entity, populating it with the information
  217.     // in configurationDigest.  If createdConfig is not nil, it is filled out with
  218.     // the information needed to choose this connection using NSHSelectConfiguration.
  219.     // You can pass nil to createdConfig if you're not interested in it.
  220.     // For Handle fields in configurationDigest, a value of nil implies that it
  221.     // should take the default.
  222.     //
  223.     // When you create a configuration, you must provide a real OTPortRef for
  224.     // any fPortRef fields in the digest.  However, you do not need to set up
  225.     // the "hint" fields of the digest.
  226.     //
  227.     // You supply any password fields in the digest in plain text form.
  228.  
  229. extern pascal OSStatus NSHDuplicateConfiguration(NSHConfigurationEntry *config,
  230.                                                  ConstStr255Param newConfigName,
  231.                                                  NSHConfigurationEntry *createdConfig);
  232.     // Duplicates the configuration specified by config, creating a new
  233.     // configuration returned in createdConfig, whose name is newConfigName.
  234.     // You can pass nil to createdConfig if you're not interested in it.
  235.     //
  236.     // These is a significant difference between duplication and create.
  237.     // When you duplicate a config, you get a copy of its preferences,
  238.     // whether they are known to this library or not.  The only difference
  239.     // is the configuration name.  When you create, the library just sets up the
  240.     // preferences it knows about.
  241.     //
  242.     // Note that making newConfigName unique is your problem.  Typically
  243.     // you do this by appending " copy" and then " copy X" until it's unique,
  244.     // handling the case where the name already ends in " copy" or " copy X".
  245.     // The caller has to do this because the intricacies are beyond the
  246.     // scope of this library.
  247.  
  248. extern pascal OSStatus NSHGetConfiguration(const NSHConfigurationEntry *config,
  249.                                                 NSHConfigurationDigest *configurationDigest);
  250.     // Returns in configurationDigest the information about the configuration
  251.     // specified by config.
  252.     //
  253.     // YOU MUST FILL OUT SOME FIELDS IN configurationDigest!!!
  254.     //
  255.     // Specifically, for Handle fields, you must either nil out the field or
  256.     // put an empty Handle in the field.  If you don't know the protocol
  257.     // associated with config, you don't know which fields are handles,
  258.     // so the only safe thing to do is zero configurationDigest.
  259.     //
  260.     // Also, for protocols which return an fPortRef, you should note that
  261.     // the returned fPortRef may be kOTInvalidPortRef.  This happens where
  262.     // a configuration is created, the port is removed (eg a PC Card is ejected)
  263.     // and you subsequently read the configuration.  You have to handle this
  264.     // case.  Typically, the protocol-specific digest will include hint fields
  265.     // that allow you to search the OT port registry for some other suitable port.
  266.     // I only mention it here because you might think that NSHSetConfiguration
  267.     // will always work if you pass it a digest generated by NSHGetConfiguration,
  268.     // but that's not true.
  269.     //
  270.     // Finally, this routine returns passwords in their encoded form.  This
  271.     // is a design decision.  If you want the decoded password, you have to
  272.     // decode it yourself.
  273.  
  274. extern pascal OSStatus NSHSetConfiguration(const NSHConfigurationEntry *config,
  275.                                                 const NSHConfigurationDigest *configurationDigest);
  276.     // Sets the configuration specified by config to the information in 
  277.     // configurationDigest.  For Handle fields in configurationDigest, a value
  278.     // of nil implies that this routine should not affect the current value.
  279.     // 
  280.     // When you set a configuration, you must provide a real OTPortRef for
  281.     // any fPortRef fields in the digest.  However, you do not need to set up
  282.     // the "hint" fields of the digest.
  283.     //
  284.     // You supply any password fields in the digest in plain text form.
  285.  
  286. extern pascal OSStatus NSHDeleteConfiguration(const NSHConfigurationEntry *config);
  287.     // Deletes the configuration specified by config.  Deleting an active
  288.     // configuration yields an error.
  289.     
  290. extern pascal OSStatus NSHRenameConfiguration(const NSHConfigurationEntry *config,
  291.                                               ConstStr255Param newConfigName,
  292.                                               NSHConfigurationEntry *newConfig);
  293.     // Renames the configuration specified by config to the name
  294.     // newConfigName.  newConfig is the returned as a reference
  295.     // to the newly renamed configuration; you can pass nil if you're not
  296.     // interested in it.
  297.  
  298. /////////////////////////////////////////////////////////////////
  299. // TCP/IP Will Dial
  300.  
  301. enum {
  302.     kNSHTCPDialUnknown = 0,
  303.     kNSHTCPDialTCPDisabled,
  304.     kNSHTCPDialYes,
  305.     kNSHTCPDialNo
  306. };
  307.  
  308. extern pascal OSStatus NSHTCPWillDial(UInt32 *willDial);
  309.     // This routine returns, in willDial, a flag indicating
  310.     // whether opening a TCP/IP provider will cause the modem 
  311.     // to dial.  You must call InitOpenTransport before calling
  312.     // this routine.  [Not because it allocates memory but
  313.     // because it calls OTInetGetInterfaceInfo.]
  314.  
  315.  
  316. /////////////////////////////////////////////////////////////////
  317. // DHCP Release
  318.  
  319. extern pascal OSStatus NSHDHCPRelease(void);
  320.     // This routine lets you force the OT TCP/IP stack to release
  321.     // any address it has aquired from a DHCP server and attempt
  322.     // to acquire a new address from scratch.
  323.     //
  324.     // The implementation is somewhat experimental.  Please
  325.     // let me know if you have problems.  Also, the non-database
  326.     // implementation is completely untested.
  327.  
  328. /////////////////////////////////////////////////////////////////
  329. // AppleTalk On/Off
  330.  
  331. extern pascal OSStatus NSHIsAppleTalkActive(Boolean *active);
  332.     // Sets *active to true if the AppleTalk stack is active.
  333.  
  334. extern pascal OSStatus HSHSetAppleTalkActive(Boolean active);
  335.     // Sets the active state of the AppleTalk stack to the active
  336.     // parameter.
  337.  
  338. /////////////////////////////////////////////////////////////////
  339. // Remote Access Password Encode
  340.  
  341. extern pascal OSStatus NSHEncodeRemotePassword(
  342.                                 ConstStr255Param userName,
  343.                                 ConstStr255Param password,
  344.                                 Str255 encodedPassword);
  345.     // Encodes a password to be compatible with the ARA
  346.     // 'pass' preference format.  Note that NSHCreateConfiguration and
  347.     // NSHSetConfiguration will automagically encode (using this routine)
  348.     // ARA passwords for you; this routine is exposed as a convenience of you
  349.     // need to encode passwords for some other reason.
  350.  
  351. /////////////////////////////////////////////////////////////////
  352.  
  353. #ifdef __cplusplus
  354. }
  355. #endif
  356.